What

Database-size lifecycle basics for EtcdCluster, in two halves:

1. Spec knobs for quota and compaction. Three new optional fields — spec.quotaBackendBytes (resource.Quantity), spec.autoCompactionMode (enum periodic/revision), spec.autoCompactionRetention (pattern-validated duration or revision count) — render the matching --quota-backend-bytes / --auto-compaction-mode / --auto-compaction-retention container args. Flags are emitted only when set, so existing clusters keep byte-identical args and nothing rolls on operator upgrade; a conflicting flag in etcdOptions still wins, following the documented precedence. A CEL rule rejects autoCompactionMode without autoCompactionRetention.

2. NOSPACE alarm surfacing. Without a quota story the operator is silent at the worst moment: when etcd hits its backend quota it raises a NOSPACE alarm and the cluster goes read-only, while the status only shows the generic UnhealthyMembers. The reconciler now polls AlarmList after the member health check (even when the health check itself errored — an alarmed member reports unhealthy, and the deferred status update still runs). An active NOSPACE alarm sets the Degraded condition with distinct reason DatabaseQuotaExceeded and emits a Warning event per affected member with the operational runbook (compact, defragment, etcdctl alarm disarm; a raised quotaBackendBytes only lands on the next StatefulSet rollout). Detection only — no defrag or disarm automation.

Files

• api/v1alpha1/etcdcluster_types.go — three fields + CEL cross-field rule.
• internal/controller/utils.go — defaultArgs/createArgs take the EtcdCluster and render the flags conditionally.
• internal/etcdutils/etcdutils.go — AlarmList + MemberAlarm (carries the alarm type string, so CORRUPT is one branch away for a follow-up), mirroring the existing client boilerplate.
• internal/controller/etcdcluster_controller.go — alarm poll in performHealthChecks, DatabaseQuotaExceeded condition reason in updateConditions (takes precedence over UnhealthyMembers), per-member Warning event, events.k8s.io RBAC marker.
• docs/configuring-etcd-options.md — new "Database size and compaction" section, including the rollout-timing caveat.
• config/crd/**, config/rbac/role.yaml, docs/api-references/docs.md, zz_generated.deepcopy.go — regenerated via make generate manifests api-docs.

Review

An adversarial review pass produced 2 blocking/important findings, both resolved in follow-up commits: the mgr.GetEventRecorder recorder emits events.k8s.io/v1 Events, so the core-group events RBAC rule alone left the DatabaseQuotaExceeded event forbidden at runtime (blocking — dedicated rule added); and the event/docs wording implied raising spec.quotaBackendBytes takes effect immediately, but steady-state reconciles never patch the pod template (important — reworded to "next StatefulSet rollout" in both places). Remaining notes were minor or deliberately descoped (below).

Testing

• TestCreatingArgs (extended table): quota rendering (8Gi → --quota-backend-bytes=8589934592), compaction mode+retention, unset fields emitting no flags, etcdOptions conflict precedence.
• TestUpdateConditionsNospaceAlarm: NOSPACE sets the distinct DatabaseQuotaExceeded reason; unhealthy-without-alarm keeps the generic reason.
• TestReportNospaceAlarms: Warning event emitted with the member name resolved from the member list; nil recorder does not panic; non-NOSPACE alarms emit nothing.
• TestAlarmList (internal/etcdutils, against a live embedded server): no active alarms, error on invalid endpoint.
• Full make test and make verify pass.

Descoped follow-ups

(1) No kubebuilder defaults for the new fields, deviating from the brief: CRD-defaulting quota/compaction to etcd's defaults would inject new container args into every existing StatefulSet and roll all clusters on operator upgrade; flags render only when set, and etcd's defaults (2GiB quota, 8GiB recommended max) are documented in the field comments. (2) Defrag automation, alarm disarm, and any LastDefragTime status field — explicit follow-up per the brief. (3) CORRUPT alarm surfacing — etcdutils.MemberAlarm carries the type string so a follow-up is one condition branch, but this PR reacts to NOSPACE only. (4) Numeric CEL bounds on quotaBackendBytes (e.g. <= 8Gi) — quantity() CEL comparisons are version-sensitive and etcd only warns above 8GiB; comment-documented instead. (5) No per-member status field for alarms and no new status API — condition + event only. (6) No sample-manifest or e2e additions (the test/e2e/etcd_options_test.go pattern would need kind); unit/fake coverage only, matching #382-sized PR precedent. (7) TLS-aware alarm client — the etcdutils helpers, including the existing healthCheck path, are already plaintext-only on origin/main; AlarmList follows the same pattern, and fixing TLS client wiring is a separate gap.

🤖 Generated with Claude Code

PR series — operability fixes, TLS & EtcdMirror

Small single-purpose PRs from live kind-cluster testing of the operator. Each stands alone unless an After is listed. → = this PR.

🟢 ready · ⚪ draft